Skip to main content

ListDataHoldsV1

A GET request that retrieves a list of your organization's data holds. The endpoint is https://api.aware.work/external/dataholds/v1.

Access​

To access this operation, your API token must have one of the following permissions:

For more information, see the API token documentation.

Request Format​

Parameters​

None of the below parameters are required. However, they can assist you in selecting the data you're looking for much more easily and efficiently than paging through all logs depending on your use-case.

To use filters, you must send the filter URL parameter along with any filters you would like to apply. Below is an exhaustive list of the filters you can use:

ParameterRequiredDescriptionTypeFormat / Options
filter=
<filter_list>		NoOnly return hold requests whose names match specified values

Default is no filtering		string
filter=isstopped:
true\|false		NoWhether to return active or inactive holds

Default is to return all holds		boolean
sort=startedOnNoGet Data Holds in ascending order of when started

This is the default sort order		string
sort=-startedOnNoGet Data Holds in descending order of when startedstring
sort=stoppedOnNoGet Data Holds in ascending order of when releasedstring
sort=-stoppedOnNoGet Data Holds in descending order of when releasedstring
limit=<count>NoReturn maximum of <count> hold requests per page

Default is 200		intinteger between 1 and 500 inclusive
more=<page token>NoGet Data Holds starting at <page token>

Default is start at beginning		string

Query​

Below is the request in its most basic form. See request samples for more advanced query examples.

curl -X GET --location "https://api.aware.work/external/dataholds/v1" \
    -H "X-Aware-Api-Key: ${API_TOKEN}"

Response Format​

If the request is successful, the API will return a 200 response and a list of matching Data Holds. It will also contain information required to access subsequent pages of Data Holds if needed:

{
  "results": [
    {
      "holdRequestModelId": "5e1177db-39c2-ed17-1195-b2e50c242cd0",
      "holdKeyType": "Email",
      "holdKey": "user@example.com",
      "name": "My hold for User",
      "startedOn": "2023-07-07T01:02:03.0004",
      "stoppedOn": null,
      "platforms": [
        "b8479d5f-4fe6-e2ec-3f10-dfc270f88816"
      ]
    }
  ],
  "advancementToken": {
    "resultSetToken": {
      "resultSetKey": "...",
      "metadata": {
        "pageSize": "1",
        "pageNumber": "2"
      }
    },
    "rowKey": null
  },
  "hasAdvancementToken": true,
  "hasResultSetToken": true,
  "hasRowKey": false,
  "totalItems": 3
}

Request Samples​

Get Data Holds with no filtering and default sort​

curl -X GET --location "https://api.aware.work/external/dataholds/v1" \
    -H "X-Aware-Api-Key: ${API_TOKEN}"

Get Data Holds that match either of two search terms​

curl -X GET --location "https://api.aware.work/external/dataholds/v1?\
    filter=userSearch,AADSearch" \
    -H "X-Aware-Api-Key: ${API_TOKEN}"

Get Data Holds in an active state​

curl -X GET --location "https://api.aware.work/external/dataholds/v1?\
    filter=isstopped:false" \
    -H "X-Aware-Api-Key: ${API_TOKEN}"

Get Data Holds in descending order of when issued:​

curl -X GET --location "https://api.aware.work/external/dataholds/v1?\
    sort=-startedOn" \
    -H "X-Aware-Api-Key: ${API_TOKEN}"

Get Data Holds in ascending order of when released:​

curl -X GET --location "https://api.aware.work/external/dataholds/v1?\
    sort=stoppedOn" \
    -H "X-Aware-Api-Key: ${API_TOKEN}"

Get Data Holds, limiting results to a maximum of 100​

curl -X GET --location "https://api.aware.work/external/dataholds/v1?\
    limit=100" \
    -H "X-Aware-Api-Key: ${API_TOKEN}"

Get another page of 100 Data Holds​

curl -X GET --location "https://api.aware.work/external/dataholds/v1?\
    limit=100\
    &more=${TOKEN_FROM_PRIOR_RESPONSE}" \
    -H "X-Aware-Api-Key: ${API_TOKEN}"